<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
  <head>
    <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
    <meta name="generator" content="AsciiDoc 8.2.5" />
    <link rel="stylesheet" href="xhtml11.css" type="text/css" />
    <link rel="icon" href="chrome://vimperator/skin/icon.png" type="image/png" />
    <script type="application/x-javascript;version=1.8" src="help.js"></script>
    <title>developer.html</title>
  </head>
<body>
<h1 style="font-size: inherit; text-align: right;">
  <span class="tag" style="float: none;">developer.html</span>
</h1>
<div class="para"><p><div style="float: right; padding-left: 1px;"> <form action="https://www.paypal.com/cgi-bin/webscr" method="post"> <fieldset class="paypal"> <input type="hidden" name="cmd" value="_s-xclick"/> <input type="image" src="" name="submit" alt="Make payments with PayPal - it's fast, free and secure!"/> <input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----MIIHPwYJKoZIhvcNAQcEoIIHMDCCBywCAQExggEwMIIBLAIBADCBlDCBjjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQKEwtQYXlQYWwgSW5jLjETMBEGA1UECxQKbGl2ZV9jZXJ0czERMA8GA1UEAxQIbGl2ZV9hcGkxHDAaBgkqhkiG9w0BCQEWDXJlQHBheXBhbC5jb20CAQAwDQYJKoZIhvcNAQEBBQAEgYBDDJfc+lXLBSAM9XSWv/ebzG/L7PTqYiIXaWVg8pfinDsfYaAcifcgCTuApg4v/VaZIQ/hLODzQu2EvmjGXP0twErA/Q8G5gx0l197PJSyVXb1sLwd1mgOdLF4t0HmDCdEI9z3H6CMhsb3xVwlfpzllSfCIqzlSpx4QtdzEZGzLDELMAkGBSsOAwIaBQAwgbwGCSqGSIb3DQEHATAUBggqhkiG9w0DBwQI8ZOwn5QkHgaAgZjjtPQxB7Vw2rS7Voap9y+xdVLoczUQ97hw+bOdZLcGykBtfoVjdn76MS51QKjGp1fEmxkqTuQ+Fxv8+OVtHu0QF/qlrhmC3fJBRJ0IFWxKdXS+Wod4615BDaG2X1hzvCL443ffka8XlLSiFTuW43BumQs/O+6Jqsk2hcReP3FIQOvtWMSgGTALnZx7x5c60u/3NSKW5qvyWKCCA4cwggODMIIC7KADAgECAgEAMA0GCSqGSIb3DQEBBQUAMIGOMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxFDASBgNVBAoTC1BheVBhbCBJbmMuMRMwEQYDVQQLFApsaXZlX2NlcnRzMREwDwYDVQQDFAhsaXZlX2FwaTEcMBoGCSqGSIb3DQEJARYNcmVAcGF5cGFsLmNvbTAeFw0wNDAyMTMxMDEzMTVaFw0zNTAyMTMxMDEzMTVaMIGOMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxFDASBgNVBAoTC1BheVBhbCBJbmMuMRMwEQYDVQQLFApsaXZlX2NlcnRzMREwDwYDVQQDFAhsaXZlX2FwaTEcMBoGCSqGSIb3DQEJARYNcmVAcGF5cGFsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAwUdO3fxEzEtcnI7ZKZL412XvZPugoni7i7D7prCe0AtaHTc97CYgm7NsAtJyxNLixmhLV8pyIEaiHXWAh8fPKW+R017+EmXrr9EaquPmsVvTywAAE1PMNOKqo2kl4Gxiz9zZqIajOm1fZGWcGS0f5JQ2kBqNbvbg2/Za+GJ/qwUCAwEAAaOB7jCB6zAdBgNVHQ4EFgQUlp98u8ZvF71ZP1LXChvsENZklGswgbsGA1UdIwSBszCBsIAUlp98u8ZvF71ZP1LXChvsENZklGuhgZSkgZEwgY4xCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJDQTEWMBQGA1UEBxMNTW91bnRhaW4gVmlldzEUMBIGA1UEChMLUGF5UGFsIEluYy4xEzARBgNVBAsUCmxpdmVfY2VydHMxETAPBgNVBAMUCGxpdmVfYXBpMRwwGgYJKoZIhvcNAQkBFg1yZUBwYXlwYWwuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEFBQADgYEAgV86VpqAWuXvX6Oro4qJ1tYVIT5DgWpE692Ag422H7yRIr/9j/iKG4Thia/Oflx4TdL+IFJBAyPK9v6zZNZtBgPBynXb048hsP16l2vi0k5Q2JKiPDsEfBhGI+HnxLXEaUWAcVfCsQFvd2A1sxRr67ip5y2wwBelUecP3AjJ+YcxggGaMIIBlgIBATCBlDCBjjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQKEwtQYXlQYWwgSW5jLjETMBEGA1UECxQKbGl2ZV9jZXJ0czERMA8GA1UEAxQIbGl2ZV9hcGkxHDAaBgkqhkiG9w0BCQEWDXJlQHBheXBhbC5jb20CAQAwCQYFKw4DAhoFAKBdMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTA3MDMyMTIyMzI1OFowIwYJKoZIhvcNAQkEMRYEFCirrvlwYVHQiNEEbM6ikfx9+Dm5MA0GCSqGSIb3DQEBAQUABIGAtbsR8GdCdURLziozXLSdtY+zJZUPPeQFXXy2V1S/3ldiN+pRvd4HI7xz8mOY1UaKJZpwZnOosy9MflL1/hbiEtEyQ2Dm/s4jnTcJng/NjLIZu+0NYxXRJhB+zMJubnMMMjzNrGlqI4F2HAB/bCA1eOJ5B83Of3dA4rk/T/8GoSQ=-----END PKCS7-----"/> </fieldset> </form> </div> <span class="vimperator-logo"></span></p></div>
<div class="para"><p><table style="border-bottom: 1px solid silver; width: 100%">
<tr style="width: 100%"><td style="width: 50%"><h2>Writing&#160;documentation</h2></td><td style="width: 50%">

 <a id="documentation"/><span class="tag">documentation</span>
 <a id="writing-docs"/><span class="tag">writing-docs</span>
</td></tr>
</table></p></div>
<div class="para"><p>For every new feature, writing documentation is <em>mandatory</em> for the patch to
be accepted. The docs are written in
<a href="http://www.methods.co.nz/asciidoc/index.html">asciidoc</a> version 8.2.x.
They are placed in the <em>src/locale/en-US/</em> directory and compiled with
<em>make doc</em>. Please refer to the
<a href="http://www.methods.co.nz/asciidoc/userguide.html">asciidoc documentation</a> above
for details. Usually you can just write text as is, and mostly it will be
interpreted correctly. The only difficult part is to write special sections
like for <a href="chrome://liberator/locale/various.html#online-help">:help</a>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>|&lt;F1&gt;| |:help| |:h| |help|
||:h[elp] {subject}|| +
||&lt;F1&gt;||
____________________________________________________________________________
Open help window.
The default section is shown unless {subject} is specified.
If you need help for a specific topic, try [c]:help overview[c].
____________________________________________________________________________</tt></pre>
</div></div>
<div class="para"><p>is displayed as:</p></div>
<p><span class="hiddentag">&lt;F1&gt;</span> <span
class="hiddentag">:help</span> <span class="hiddentag">:h</span> <span
class="hiddentag">help</span>

<div class="key">:h[elp] <span class="argument">&#123;subject&#125;</span></div><br />
<div class="key">&lt;F1&gt;</div></p>
<div class="quoteblock">
<div class="quoteblock-content">
<p>Open help window.
The default section is shown unless <span class="argument">&#123;subject&#125;</span> is specified.
If you need help for a specific topic, try <span class="command">:help overview</span>.</p>
</div></div>
<div class="para"><p>Some notes about the code above:</p></div>
<div class="ilist"><ul>
<li>
<p>
<strong><span>|&lt;F1&gt;|</span></strong> defines a <em>tag</em>. A tag is written at the right in magenta and let's
  you jump to a topic with <a class="command" href="#">:help &lt;F1&gt;</a>. Note that you must write it from
  right to left, so in the above example <span>|help|</span> will be the most left tag,
  and <span>|&lt;F1&gt;|</span> the most right one.
</p>
</li>
<li>
<p>
<strong><span>||:h[elp] {subject}|| +</span></strong> and <strong><span>||&lt;F1&gt;||</span></strong> define command or mapping
  names and are printed on the left side. Note the + at the end of one
  command, that indicates a new line. There is no general rule when a new line
  is needed and when not, just try it out and see what looks better.
</p>
</li>
<li>
<p>
The actual help code for this command is embedded in at least 4 underscores
  (_). This generates a quoteblock and indents the text so it is more clear
  that it belongs to the command.
</p>
</li>
<li>
<p>
Wrap things in <strong><span>[c]</span></strong> and they are drawn like a :command. Also <strong><span>[o]</span></strong>,
  <strong><span>[m]</span></strong> and <strong><span>[a]</span></strong> are available to markup options, mappings, and
  arguments.
</p>
</li>
<li>
<p>
As a convenience, any string within {&#8230;} and <span>[count]</span> and <span>[!]</span> are
  automatically marked up as an argument.
</p>
</li>
</ul></div>
<div class="para"><p>There are also some additional asciidoc commands specifically for writing
Vimperator documentation:</p></div>
<div class="ilist"><ul>
<li>
<p>
<strong><span>section:Writing{nbsp}documentation[writing-docs,documentation]</span></strong> Creates
  a new section like <em>Writing Documentation</em> in this help file with 2 tags.
</p>
</li>
<li>
<p>
<strong><span>help:developer{nbsp}information[developer.html#documentation]</span></strong> creates
  a link with text <em>developer information</em> to the tag <em>documentation</em> in
  the file <em>developer.html</em>.
</p>
</li>
</ul></div>
<div class="para"><p>If you don't know in which file/section you should put some documentation, ask
on the mailing list or on #vimperator. Usually help should be grouped together
in logically connected subject areas like
<a href="chrome://liberator/locale/browsing.html#opening">opening&#160;web&#160;pages</a>.</p></div>
<div class="para"><p><table style="border-bottom: 1px solid silver; width: 100%">
<tr style="width: 100%"><td style="width: 50%"><h2>Generating&#160;documentation</h2></td><td style="width: 50%">


 <a id="generating-docs"/><span class="tag">generating-docs</span>
</td></tr>
</table></p></div>
<div class="para"><p>You can also autogenerate most of the asciidoc help after you have written a
new command, mapping or option. For this, use:</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>:echo util.generateHelp(commands.get("addons"), "Extra text")</tt></pre>
</div></div>
<div class="para"><p>Now you can copy the asciidoc text but always make sure it looks OK after
you compile the help file with "make doc", as the auto-generation might
not work correctly for all special cases.</p></div>
<div id="footer">
<div id="footer-text">
Last updated 2009-02-28 20:06:33 IST
</div>
</div>
</body>
</html>
